Level Builder Documentation

The level editor that ships with Midnight Mansion is both easy and fun to use. It has been designed to be easy enough that anyone can create professional-quality levels for the game in no time. 


Getting Started

When you first start up the editor, it will present you with a dialog box. Select the mansion file you wish to edit. If you want to create a new mansion, first duplicate the file "Empty Mansion" (in the Custom Mansions folder) and rename it. Then open this with the editor.

After you open a mansion, you will see a grid of all of the rooms in that mansion. Just double-click on the room you want to open, or use the arrow keys.

TIP: if you open a mansion that came with the game, you'll see a lot of "?" rectangles instead of preview pictures of the rooms. That is because the preview pictures are removed before shipping the game to cut down on download size. Just cancel the Open dialog, then choose "Create Preview PICTs" from the Special menu, and the next time you choose Open, you'll see a nice preview of the mansion.

To open a different room, choose "Open Room..." from the File menu. Or to open a different file containing other rooms, choose "Open File..." from the File menu.

WARNING: Do not modify any of the mansions in the Midnight Mansion -> Mansions folder. If you do, you won't be able to play them from within the game, except by doing "Open Mansion..." and playing them as you would a 3rd party mansion. This is because if the game allowed you to play modified mansions, anyone could simply fill a mansion with hundreds of money bags and then submit an obscenely large high score to the web site. If you want to modify mansions that came with the game, be sure to make a copy of them first, and modify the copy.


Editing

Editing rooms is both easy and intuitive. Simply click on the object you wish to place in the room, using the two scrollable areas at the top of the screen, then click in the room to place that object. 

The objects in the upper-left area are "tiles", while the objects in the upper-right are "Sprites". Typically, tiles are stationary, like walls, but can also be animated, like the conveyor belts. Sprites usually move around. All of the enemies are sprites, as are all of the objects you can collect in the game, such as keys.

If you place the hero in a room, this is where he will start if you select "Test Room..." for that room.


Testing Rooms

Use "Test Room" in the File menu to test your creation. It's a good idea to place the main character in the room before you test it, otherwise you won't be able to play. If you have not saved the room before testing, the editor will prompt you to do so. The Test Room option allows you to instantly test any change you've made to any part of your room, making level-editing a breeze. Say goodbye to old-fashioned editors that make you quit and start up the game before you can test your changes!

Press the Esc key at any time to exit back to the editor. You will also return to the editor when you lose all your lives.

If you want to test your mansion using the game itself, and not the editor, be sure to move your mansion into the "Custom Mansions" folder, since otherwise, suspended games, movies, and saved games won't work properly -- they won't know where to find your mansion.


Setting the Starting Room

The editor allows you to put the hero's sprite in as many rooms as you want for testing purposes, but the game won't know what room you want the player to start in when they start playing your mansion. To set the starting room, first open the room you want the player to start in, then choose "Room Options..." from the File menu to see that Room's ID, then choose "Mansion Options..." from the File menu and enter that value in the Starting Room field.


Setting the Music

You can have the music change as often as you would like as the player progresses throughout your mansion. First open a room where you would like the music to change, then choose "Room Options..." from the File menu and enter an index in the "Music Index" field. Enter an index of 1 through 4 to play any of the music files that ship with the game. Entering an index of 0 will result in no change to the currently playing music when the user enters the room you are editing. Most of your rooms will likely contain an index of 0, so that you only have to enter indexes at the points where the music changes. However, be sure that when the music changes, you enter an index not only in the room where it changes, but you also enter the previously playing music in the previous room, so the music changes back if the player goes back. You may use an index of -1 to have no music play in that room, as well as any connecting rooms of index 0.

NOTE: Be sure to enter a music index in your starting room, otherwise there will be no music when someone starts playing. 

You may also add custom music and instruct users to add this to their Music folder. In that case, you would name your music "Background Music X" where X is an index greater than 4. Then choose this index in "Room Options...." 


Deleting Rooms

To delete a room, you must first choose "Open Room..." from the File menu, then select the room you wish to delete and click the Delete button in the dialog box. A confirmation dialog ensures you don't delete any rooms by accident.


Moving Rooms

If you find you want to move a room to a different location on the grid, just use the "Save Room As..." command to save it to a different location, then use Delete to delete the original copy.


Tile Layers

The "Current Layer" menu indicates the current layer in which tiles will be drawn. (Layers do not affect sprites.) Most of your drawing will occur in the default layer, layer 4. This is where you will draw all of the bricks, conveyor belts, energy beam floors, lava, vines, and poles. Ladders must be drawn in another layer, and background tiles must be drawn in the bottom-most layer. The layer setup is as follows:

layer 0 - Background tiles
layer 4 - Main tiles (bricks, platforms, vines, poles, etc.)
layer 5 - Ladders
layer 6 - Anything you want to appear in front of the sprites. Also used for "secret passages." Sprites will not collide with anything in this layer.

Do not draw in layers 1-3. These are used by the editor to draw the pseudo-3D fringe for the bricks and other tiles. This is done for you automatically, so you may not even realize it's happening.


The Tools

In the left of your screen is a toolbar containing various tools that will make your life easier. Most are pretty intuitive. Here's what each tool does:

- Black arrow:  Use this to place tiles or Sprites. 

- Red arrow: Select this, then click on a sprite to edit its properties. See the section "Editing Sprites" below for more information.

- Eraser tool:  This erases Sprites.

- Selection tool:  Select an area with this tool to move, copy, cut, clear, or duplicate that selection. Use the edit menu for most operations, or the keyboard as a shortcut. Press Delete to clear the selection, or hold the option key while dragging the selection to make a copy of it.

- Fill tool:  When clicked on a tile, this fills that area with the currently selected tile. The fill tool is for use with tiles only.

- Rectangle tool:  Use this to draw a rectangle of tiles.

- Line tool:  Use this to draw a line of tiles.

Eye-dropper tool:  This handy tool allows you to quickly select an object by clicking on it in the main window, without having to find it in the Tile or Sprite areas. Shortcut: hold Option to temporarily activate the eye-dropper tool.

Hand tool:  This lets you easily scroll around the editor view. Shortcut: hold Control to temporarily activate the Hand tool. 


Editing Sprites

When you click on sprites with the red mouse tool, you are presented with a dialog box of choices that changes from sprite to sprite. Some sprites can't be configured, and only let you view their objectID, which is used in connection with the levers (see below). But many sprites can be edited. Here is a list of some of them:

- Almost all enemies. In most cases, you can set their starting direction and speed. For some, such as the small spiders and skeleton fish, you can control even more options.
- Walking skeletons: These are harmless piles of bones until something triggers them to uncollapse into a skeleton and chase the player. They can be set to come alive when the player steps on a brick switch (use either "Turn Sprite ObjectID ON" or the "Make all skeletons come alive" options), or when the players gets within a certain range, or after a certain amount of time passes from when the player first walks into the room.
- Zapper nodes: you can control when the zapper beam turns on, how long it stays on, and how long it stays off. By changing when the beam turns on, you can create several zapper beams that each turn on one after the other, for a staggered pattern. There is room for a lot of interesting variation here. Click on the bottom or right node to set the beam options.
- Moving platforms: you can control their speed, and whether they move horizontally or vertically. You can also set whether they are initially moving. (This option allows for some interesting puzzles when levers toggles whether all platforms are moving or not.)
- Keys, Shield, Lantern: you can check a box that makes these objects fall, and therefore ride on moving platforms and conveyor belts. Useful for puzzle rooms, where a lever might change the direction of a conveyor belt, which in turn pushes a key off the edge, and into your reach.
- Paintings: you can select where the painting is "foreground" or "background." Select foreground if you wish the painting to appear in front of the bricks in tile layer 4, since otherwise, it will disappear behind these bricks when you play the room.
- Doors: you can select whether they are open or closed to start. (Again, useful for puzzles with levers.)
- Torches: you can select whether they are lit or unlit to start.
- Levers: see the special section below, describing all of the lever's options in detail.
- Raised brick switches: these can perform all of the actions that a lever can, but might be triggered accidentally by an unobservant player. Unlike the lever, these don't toggle things -- they only turn them on or off.


Levers

When you click on a lever with the red mouse tool, you are presented with a number of options that are worth describing here. First, you have a pop-up menu with a variety of actions the lever can perform. These options are as follows:

Affect Sprite ObjectID - This performs different actions depending on the type of sprite. When you select this option, you must enter the objectID of a Sprite that is in the same room as the lever. The lever can affect the following kinds of sprites:
  - Doors: the door will open. Intended for use with gray doors, which can't be opened with keys.
  - Trap doors: will open the trap door, or more than one if another door is touching the affected door.
  - Moving platforms: the lever will stop/start the moving platform.
  - Zapper nodes: turns a single zapper beam on/off.

Change One Moving Platform - This is the only option besides "Affect SpriteID" that requires you to enter an objectID. The lever will change the direction of one moving platform.

Change All Moving Platforms - This changes the direction of all moving platforms in the current room only. The "ObjectID to affect" field is ignored.

Change Conveyor Belts - This will change the direction of all conveyor belts in the current room only. The "ObjectID to affect" field is ignored.

Start/Stop Moving Platforms - Toggles every moving platform in the current room between moving and not moving. The "ObjectID to affect" field is ignored.

Start/Stop Conveyor Belts - Turns every conveyor belt in the current room on/off. The "ObjectID to affect" field is ignored.

Start/Stop All Zapper Beams - Turns every zapper beam in the current room on/off. The "ObjectID to affect" field is ignored.

Toggle Disappearing Bricks - The only action that affects rooms besides the one the lever is in, this lever toggles gold/silver disappearing bricks. One set disappears while the other appears each time the lever is pulled.

Open All Trap Doors - Opens every trap door in the current room.

Open All Gray Doors - Opens every gray door in the current room. The lever can be pulled only once with this action.

Toggle All Gray Doors - Opens doors that are closed, while simultaneously closing any open doors. You can set up some interesting puzzles by setting certain doors to be open to start, in combination with this lever option. (Click on a door using the edit sprite tool to set it to be open to start.)

Toggle All Torches - Extinguishes torches that are lit, while simultaneously lighting currently unlit torches.




Levers also have three checkboxes you can use to customize how the lever works:

"Lever is reset when re-entering room" - This is useful for certain puzzle rooms, where, for instance, a trap door might release a key, and the key could fall in the lava if you do it wrong. If this box is checked, the player can leave the room, and when they come back, everything is back to normal -- the trap door will be closed, the key is in its original location, and the lever can be pulled to open it again. 

Note: it would not make much sense to use this option in combination with the "Toggle Disappearing Bricks" option, since that is a global option that affects all rooms, and having the lever reset its handle while the bricks remain unchanged would be confusing.

Note 2: It is recommended that you do NOT use this option for a lever in the same room as a save pedestal, since otherwise, when the player dies and is restored in the room, the room may be in a different state than when he left it, due to the lever getting reset.

"Lever can be pulled only once, unless reset." - If checked, the lever can be pulled only once. If the player tries to pull it again, it won't budge. However, if the first check box is also checked, so that the lever is reset every time the player re-enters that room, then they will be able to pull it again..

"Action is default room state." - When checked, the selected lever action is the default state for the room, and pulling the lever undoes that state. For instance, if the action is "Start/Stop Conveyor Belts," and this box is checked, conveyor belts will be stopped when you first enter the room, and pulling the lever will start them up again. Note that if you select this check box for more than one lever that performs the same action, the second lever will undo the effects of the first one. NOTE: This checkbox is ignored when the "Toggle Disappearing Bricks" option is selected, since that is a global action.

NOTE: this option is ignored for "Affect Sprite ObjectID" when the sprite being affected is a door or trap door. (To make a door open to start, select it with the red mouse tool and click the "Open to start" check box.)

Lever Handle Colors

While it's possible to use any lever handle color for any action, you should follow these guidelines, so players have some idea what your lever will do before they pull it:

Red - change conveyor belt direction OR open trap doors (i.e. affect red objects)
Blue - Turn zapper beams on/off 
Brown - Toggle gold/silver bricks OR open gray doors
Green - Misc (everything else, like start/stop conveyor belts,
start/stop moving platforms, or other misc. actions)


Brick Switches

The raised brick switches perform actions similar to the lever, although the brick switch isn't used to toggle an object's state; it instead typically turns it either off or on. See the section on levers above to learn more about performing actions. Brick switches can affect the same sprites as the levers. Sometimes they can do additional things the lever can't. (Move torch's flame forward/backward, make one or all walking skeletons come alive, etc.)

NOTE: don't confuse brick switches with moving platforms! They look almost identical. In the editor's list of sprites, the moving platforms are all grouped together, and the brick switches are next to the levers.


Special Tiles

Some tiles in the game may need special handling you might not figure out on your own. Here is a description of most of these. 

Ladders

You may notice that there are special tiles for the top and bottom of the ladders, where the handle sticks out. The game uses these tiles to tell where the ladder starts and ends. Make sure to use these whenever your ladder ends, or else Jack may not climb off of it correctly. This is especially true of ladders that go both up and down from a brick ledge -- the parts of each that touch the ledge must use the proper bottom and top tiles of the ladder.

Note that you MUST draw ladders in tile layer 5, otherwise Jack can't use them.

Note: ladders or anything else drawn in layers 5 and 6 over lava will be covered up by the lava when you play the game.

Carpet

The carpet should typically be drawn in layer 5, so that is shows up underneath the hero, but above the bricks its laying on top of. However, if you want to put a ladder over a carpet, you can do so by moving the portion of the carpet that will be directly under the ladder into layer 4. (Make sure that this doesn't include the left or right edges of the carpet -- only the middle.)

Gold/Silver Bricks

These aren't ordinary bricks. Only one of them is visible at a time. The lever or brick switch toggles which one is visible.

Background tiles / Foreground tiles

Most of the tiles to the right of the lava are "background tiles" intended to be drawn in layer 0. On the very far-right are some "foreground" tiles, such as pillars, that are typically drawn in layer 6, but sometimes in other layers. 



The Edit Menu

While most options of the edit menu are only available while something has been selected or copied with the Selection tool, one option is available almost all of the time, and is very, very useful: Undo. Use this after almost any action to undo it, including any change you make to your room, whether it be a fill operation that went wrong, or an accidental deletion of a portion of the room. After Undoing something, you can Redo it.

Some operations can not be undone, such as deleting a room, "Shift TileIDs...." or "Shift SpriteIDs...".


The Special Menu

Redraw fringe in this room - this option fixes fringe that may have been messed up somehow. Fringe is the pseudo-3D portion of tiles that is drawn above and to the right of each tile. It is drawn automatically by the editor, and is put in tile layers 1-3. If somehow the fringe becomes messed up, you can choose this option to redraw it.

Draw brick fringe in layer 6 - this option is designed to help you hide your secret passages better. Normally, bricks in layer 6 have their fringe automatically drawn. However, this can make secret passages too obvious, since that fringe shows up in front of normal bricks in layer 4. I find the easiest way to fix this is to draw your fake bricks where you want, then turn automatic fringe drawing off and erase the fringe that you don't wany from layer 6.

Create Preview PICTs - If you open up a mansion, and most or all of the room previews show red question marks instead of a preview of each room, choose this option to redraw preview. It takes a minute or so to redraw everything.

Remove Preview PICTs - Call this before compressing and uploading your mansion for others to download. That is because preview PICTs add a lot to a mansion's size when it is compressed, and they can easily be re-created using the option above when a person downloads your mansion, if they wish to edit it.




Shortcuts

Hold Option to temporarily change the current tool into an eye-dropper. This is a great time-saver! Much editing can be done without ever having to select anything from the tile or sprite menus.

Hold Command to temporarily change the current tool to the Hand tool.

To change the current tool, press 1-9 on the keyboard.

To clear the entire room, including sprites, choose Select All (Command-A) from the Edit menu and hit the Delete key. Repeat for each layer you want cleared.


Tips

- To set the starting room, so that the game can be played from within the game using the "Open mansion..." button on the difficulty screen, make sure you first select a starting room number by choosing "Choose starting room..." from the File menu.

- If you are drawing bricks, and don't see see the pseudo-3D top and right sides on them, this means you are in the wrong layer. Delete what you drew, change to layer 4, and try again.

- To easily connect one room with another, so that the doorway is in exactly the same place in each room, use the selection tool to copy the row of tiles leading to the other room. Then open the other room and paste, moving the tiles to the opposite side. Repeat the process, this time in tile layer 5, to copy ladders.

- To draw objects that are made out of many tiles, such as the ladder, pillars, or background windows/jail cells, make heavy use of Copy and Paste!!! It's painful to have to put these objects together one tile at a time, but it's easy with copy and paste. Personally, I create a special room in my levels file where I put these all together once, then I just open that room and copy & paste whenever I need to draw one of those objects. The "Empty Mansion" file already has many rooms with ready-to-copy objects already assembled, and each in their proper layer. It is highly recommended that you duplicate the Empty Mansion file to behind your own mansion.

- To draw "secret passages" where you can move behind the bricks, simply draw the bricks in layer 6. But beware that these bricks will appear to be drawn "in front" of any other bricks. To avoid this look, turn off fringe using the Special menu. You may have to play with drawing a bit to get it right. It also might be helpful to use the selection tool and delete unwanted parts.

- The background arches and jail cells can be made any size by repeating tiles. Likewise, windows can be made taller by filling in the middle with black tiles from any other part. (There are some plain black tiles in the middle of the arches that can be used for this.)


The Options Menu

The "Resize Room..." option isn't used by Midnight Mansion, and is dimmed out.

Use "Select Background..." to choose the background pattern used by this room. Typically the background pattern doesn't matter, since you will use tiles to draw your background in tile layer 0.

Use the "Fill border with tile" command to instantly fill the border of your room with the currently selected tile. This operation can be undone.

The "Fill layer with tile" command fills the current layer with the currently selected tile, without erasing any of the Sprites. If you wish to erase all of the Sprites too, simply Select All, hit Delete, then fill the layer with your tile.

The "Replace Tile..." command lets you replace all tiles of one type with another tile. The tiles are numbered starting at 0; this is called the tileID. So the black (empty) tile is 0, the next is tileID 1, and so on. In "Replace Tile", you select the tile you wish to replace, then enter the tileID of the tile you want to replace it with.

The "Shift TileIDs..." and "Shift SpriteIDs..." options were used during development, and should be used only if you know what you're doing!!! If you enter values in these dialogs, AND choose "Change all levels," you can mess up your entire mansion in one fell swoop. You aren't likely to need these commands for anything, so steer clear!

The "Fix Invalid TileIDs..." was used during development. You won't likely ever need to use it. 

The "Reset ObjectIDs...." command should be used whenever you copy and paste a section of a room from one file into another levels file, since you may have pasted in objects that have the same IDs as other objects in your room. The game uses object IDs to keep track of the extra life and bonus gem items. (Each one needs a unique ID, which the editor automatically assigns when you save your room.) The ObjectIDs are automatically reset whenever you quit, so you probably won't ever need to select this option.

The "Align to Grid" option allows you to place sprites freely, without being constrained to a grid while placing them. This is primarily intended to allow you to place paintings wherever you want, but could also be used to place enemies. Note, however, that some sprites, such as the zapper nodes and doors, were designed to be placed with the grid turned on, and will give bad results if placed without the grid.




Full Screen Mode

For those who are using a 640x480 display resolution, and can't see the entire room at once in the editor, full-Screen mode allows you to immerse yourself in the room you're designing, to get a good feel of how it will look once you're actually playing it. This mode often helps get the creative juices flowing, as well as being an easy mode to work in.

To enable full-screen mode, choose it from the Options menu, or just hit Command-F. Press Command-F again or Esc to exit full-screen mode. Remember that you can change tools by hitting the number keys, and that you can quickly use the eyedropper tool by pressing Option. This means you can select tiles or Sprites if they've already been placed in the room, without having to exit full-screen mode. 

Hold the Command key while in Full-Screen mode to temporarily show the menu bar.


Known Limitations

The selection tool, as well as Copy and Paste, handles only one tile layer at a time. If you wish to copy a portion of one room to another, you may need to make several "trips," copying different layers each time. Beware that when pasting a large area, any sprites below the selection being pasted will be overwritten by whatever is in the selection.
